<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>timer_create</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_010_025">&nbsp;</a>NAME</h4><blockquote>
timer_create - create a per-process timer
(<b>REALTIME</b>)
</blockquote><h4><a name = "tag_000_010_026">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="time.h.html">time.h</a>&gt;
#include &lt;<a href="signal.h.html">signal.h</a>&gt;

int timer_create(clockid_t <i>clockid</i>, struct sigevent *<i>evp</i>,
    timer_t *<i>timerid</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_010_027">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>timer_create()</i>
function creates a per-process timer using the specified clock,
<i>clock_id</i>,
as the timing base.
The
<i>timer_create()</i>
function returns, in the location referenced by
<i>timerid</i>,
a timer ID of type
<b>timer_t</b>
used to identify the timer in timer requests.
This timer ID will be unique within the calling process
until the timer is deleted.
The particular clock,
<i>clock_id</i>,
is defined in
<i><a href="time.h.html">&lt;time.h&gt;</a></i>.
The timer whose ID is returned will be in a disarmed state upon return from
<i>timer_create()</i>.
<p>
The
<i>evp</i>
argument, if non-NULL, points to a
<b>sigevent</b>
structure.
This structure, allocated by the application,
defines the asynchronous notification 
to occur as specified in
<xref href=siggendel><a href="sigaction.html#tag_000_008_581_001">
Signal Generation and Delivery
</a></xref>
when the timer expires.
If the
<i>evp</i>
argument is
<b>NULL</b>,
the effect is as if the evp argument pointed to a
<i>sigevent</i>
structure with the
<i>sigev_notify</i>
member having the value SIGEV_SIGNAL, the
<i>sigev_signo</i>
having a default signal number, and the
<i>sigev_value</i>
member having the value of the timer ID.
<p>
Each implementation defines a set of clocks that can be used as timing
bases for per-process timers. All implementations support a
<i>clock_id</i>
of CLOCK_REALTIME.
<p>
Per-process timers are not inherited by a child process across a
<i><a href="fork.html">fork()</a></i>
and are disarmed and deleted by an
<i>exec</i>.
</blockquote><h4><a name = "tag_000_010_028">&nbsp;</a>RETURN VALUE</h4><blockquote>
If the call succeeds,
<i>timer_create()</i>
returns zero and updates the location referenced by
<i>timerid</i>
to a
<b>timer_t</b>,
which can be passed to the per-process timer calls.
If an error occurs,
the function returns a value of -1 and sets
<i>errno</i>
to indicate the error.
The value of
<i>timerid</i>
is undefined if an error occurs.
</blockquote><h4><a name = "tag_000_010_029">&nbsp;</a>ERRORS</h4><blockquote>
The 
<i>timer_create()</i>
function will fail if:
<dl compact>

<dt>[EAGAIN]<dd>
The system lacks sufficient signal queuing resources to honour the request.

<dt>[EAGAIN]<dd>
The calling process has already created
all of the timers it is allowed by this implementation.

<dt>[EINVAL]<dd>
The specified clock ID is not defined.

<dt>[ENOSYS]<dd>
The function
<i>timer_create()</i>
is not supported by this implementation.

</dl>
</blockquote><h4><a name = "tag_000_010_030">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_010_031">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_010_032">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_010_033">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="timer_delete.html">timer_delete()</a></i>,
<i><a href="clock_gettime.html">clock_gettime()</a></i>,
<i><a href="clock_settime.html">clock_settime()</a></i>,
<i><a href="clock_getres.html">clock_getres()</a></i>,
<i><a href="timer_gettime.html">timer_gettime()</a></i>,
<i><a href="timer_settime.html">timer_settime()</a></i>,
<i><a href="time.h.html">&lt;time.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

